<?php
// $Id$
/**
 * This file contains {@link VetoableEventListener} which is part of the PHP 
 * Content Repository (phpCR), a derivative of the Java Content Repository 
 * JSR-170, and is licensed under the Apache License, Version 2.0.
 *
 * This file is based on the code created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 * @subpackage Level2
 */

/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/../phpCR.library.php');
phpCR::loadInterface('Event', '/event');


/**
 * A vetoable event listener.
 *
 * Level 2 only
 *
 * A {@link VetoableEventListener} can be registered via the 
 * {@link ObservationManager::addVetoableEventListener()} method.
 *
 * Vetoable event listeners may veto the action that the events represent. If an
 * {@link Event} is vetoed, the corresponding action is forbidden by the 
 * repository.
 *
 * Vetoable listeners are notified synchronously, and see events prior to the
 * repository acting upon them. A vetoable listener only sees events for which
 * the {@link Ticket} that registered it has sufficient access rights.
 *
 * To veto an event, a class implementing the {@link VetoableEventListener}
 * interface returns true from the {@link onEvent()} method. If this happens
 * during a transaction, the transaction is rolled back. If multiple vetoable
 * listeners are registered, the first listener to veto an event causes the
 * original operation to fail. No other vetoable listener is invoked.
 *
 * @author PHP - Travis Swicegood <travis@domain51.net>
 * @copyright Copyright &copy; 2004-2005, Domain51
 * @package phpContentRepository
 * @subpackage Level2
 */
public interface VetoableEventListener 
{
   /**
    * Performs some action upon receipt of the event. 
    *
    * Returning FALSE will cause the operation in question to 
    * proceed,, returning TRUE will veto the operation in question.
    *
    * @param object
    *   The {@link Event} object to check
    * @return bool
    */
    public function onEvent(Event $event);
}

